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1. Art OVERVIEW OF CP/M 2.0 FACILITIES. 


CP/M 2.0 is a nigh-performance single-console operating system 
wnicn uses table driven tecnnigues to allow field reconfiguration to 
match a wide variety of disk capacities. All of the fundamental file 
restrictions are removed, while maintaining upward compatibility from 
previous versions of release 1. Features of CP/M 2.0 include field 
specification of one to sixteen logical drives, each containing up to 
eignt megabytes. Any particular file can reacn the full drive size 
witn the capaoility to expand to thirty-two megabytes in future 
releases. The directory size can be field configured to contain any 
reasonable number of entries, and each file is optionally tagged with 
read/only and system attributes. Users of CP/M 2.0 are physically 
separated oy user numoers, with facilities for file copy operations 
from one user area to another, powerful relative-record random access 
functions are cresent in CP/M 2.0 wnicn provide direct access to any 
of the 65536 records of an eight megaoyte file. 

All disk-dependent portions of CP/M 2.0 are placed into a 
3I0S-r esident "disk parameter block" wnicn is either hand coded or 
produced automatically using the disk definition macro library 
provided with CP/M 2.3. The end user need only specify the maximum 
numoer of active disks, the starting and ending sector numoers, the 
data allocation size, the maximum extent of the logical disk, 
directory size information, and reserved track values. The macros use 
this information to generate tne appropriate taoles and table 
references for use during CP/M 2.3 operation. Deblocking information 
is also provided wnicn aids in assembly or disassembly of sector sizes 
wnich are multiples of tne fundamental 128 Dyte data unit, and the 
system alteration manual includes general-purpose subroutines wnich 
use tne tnis deblocking information to take advantage pf larger sector 
sizes. Use of these subroutines, together with the ta*ole driven data 
access algorithms, make CP/M 2.3 truly a universal data management 
system. 

File expansion is achieved oy providing up to 512 logical file 
extents, where eacn logical extent contains 16K bytes of data. CP/M 
2.0 is structured, however, so that as much as 123K bytes of data is 
addressed by a single physical extent (corresponding to a single 
directory entry) , thus maintaining compatibility with previous 
versions while taking full advantage of directory space. 

Random access facilities are present in CP/M 2.0 which allow 
immediate reference to any record of an eight megabyte file. Using 
CP/M’s unique data organization, data blocks are only allocated when 
actually required and movement to a record position requires little 
search time. Sequential file access is upward comoatiole from earlier 
versions to the full .eight megaoytes, wniie random, access 
compatibility stops at 512K byte files. Due to CP/M 2.0’s simoler and 
faster random access, application orogrammers are encouraged to alter 
their programs to take full advantage of the 2.0 facilities. 

Several CP/M 2.0 modules and utilities have improvements whicn 
correspond to the enhanced file system. STAT and PIP both account for 
file attributes and user areas, while the CCP provides a "login" 
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function to change from one user area to anotner. The CCP aiso 
formats directory displays in a more convenient manner and accounts 
for doth CRT and hard-copy devices in its enhanced line editing 
functions. 

The sections below point out the individual differences between 
CP/M 1.4 and CP/M 2.0, with the understanding that the reader is 
either familiar witn CP/M 1.4, or has access to the 1.4 manuals. 
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2. USER INTERFACE. 


Console line processing takes CRT-type devices into account with 
tnree new control characters, shown with an asterisk in the list below 
(the symbol "ctl" below indicates tnat the control key is 
simultaneously depressed) : 

rub/del removes and ecnoes last character 
ctl-C reDoot when at beginning of line 
ctl-E physical end of line 
ctl-H oackspace one cnaracter position* 
ctl-J (line feed) terminates current input* 
ctl-M (carriage return) terminates input 
ctl-R retype current line after new line 
ctl-U remove current line after new line 
ctl-X Dackspace to beginning of current line* 

In oarticular, note that ctl-H produces the proper backspace overwrite 
function (ctl-H can be changed internally to anocner cnaracter, such 
as delete, througn a simple single byte change). Furtner, the line 
editor keeps track of the current prompt column position so that the 
operator can properly align data input following a ctl-U, ctl-R, or 
ctl-X command. 
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3 o CONSOLE COMMAND PROCESSOR (CCP) INTERFACE 


there are four functional differences between CP/M 1.4 and CP/M 
2.0 at the console command processor (CCP) level. The CCP now 
displays directory information across the screen (four elements per 
line) , the USER command is present to allow maintenance of separate 
files in the same directory, and the actions of the “ERA *.*“ and 
"SAVE" commands have changed. The altered DIR format is 
self-explanatory, while the USER command takes the forms 

USER n 

where n is an integer value in the range 0 to 15. Upon cold start, 
tne operator is automatically “logged" into user area number 0, which 
is compatible with standard CP/M 1.4 directories. Tne operator may 
issue the USER command at any time to move to anotner logical area 
within the same directory. Drives which are logged-in while 
addressing one user number are automatically active when the operator 
moves to another user numoer since a user number is simply a prefix 
which accesses particular directory entries on the active disks. 

The active user number is maintained until changed by a 
subsequent USER command, or until a cold start operation when user 0 
is again assumed. 

Due to the fact that user numbers now tag individual directory 
entries, tne ERA *.* command has a different effect. In version 1.4, 
this command can oe used to erase a directory wnicn has "garDage" 
information, perhaps resulting from use of a diskette under another 
operating system (heaven forbid!). In 2.0, however, the ERA *.* 
command affects only the current user numoer. Thus, it is necessary 
to write a simple utility to erase a nonsense disk (the program simply 
writes the hexadecimal pattern E5 throughout the disk) . 

The SAVE command in version 1.4 allows only a single memory save 
operation, with the potential of destroying the memory image due to 
directory operations following extent boundary changes. Version 2.3, 
nowever, does not perform directory operations in user data areas 
after disk writes, and thus the SAVE operation can be used any number 
of times without altering the memory image. 
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4. 5 TAT ENHANCEMENTS. 


The STAT program has a number of additional functions which 
allow disk parameter display, user number display, and file indicator 
manipulation. The command: 


STAT VAL: 

produces a summary of the available status commands, resulting in the 
output: 

Temp R/O Disk: d:=R/0 

Set Indicator: d : f ilename . tyD $R/0 $R/N $SYS $DIR 
Disk Status : DSK: d :D5K: 

User Status : USR: 

Iobyte Assign: 

(list of possible assignments) 

whicn gives an instant summary of the possible STAT commands. The 
command form: 

STAT d:f ilename. tvp $S 

wnere "d:“ is an optional drive name, and "filename. typ" is an 
unamDiguous or ambiguous file name, produces the output display 
format: 


Size 

Rees 

Bytes 

Ext 

ACC 


48 

43 

6k 

1 

R/0 

A: ED. COM 

55 

55 

12k 

1 

R/0 

(A :P IP. COM) 

6 5536 

128 

2k 

2 

R/N 

A.-X.DAT 


where tne SS oarameter causes the “Size" field to be disolayed 
(without the $S, the Size field is skipped, but the remaining fields 
are displayed) . The Size field lists the virtual file size in 
records, while the "Rees" field sums the number of virtual records in 
each extent. For files constructed sequentially, the Size and Rees 
fields are identical. The ••Bytes" field lists the actual number of 
bytes allocated to the corresponding file. The minimum allocation 
unit is determined at configuration time, and thus tne number of bytes 
corresponds to the record count plus the remaining unused space in the 
last allocated block for sequential files. Random access files are 
given data areas only wnen written, so the Bytes field contains the 
only accurate allocation figure. In the case of random access, the 
Size field gives the logical end-of-file record position and the Rees 
field counts the logical records of each extent (each of these 
extents, however, may contain unallocated "holes" even though they are 
added into the record count) . The "Ext" field counts the number of 
logical 16K extents allocated to the file. Unlike version 1.4, the 
Ext count does not necessarily correspond to the number of directory 
entries given to the file, since there can be up to 128K oytes (8 
logical extents) directly addressed oy a single directory entry, 
depending upon allocation size (in a special case, there are actually 
256K bytes which can be directly addressed by a physical extent) . 

The "Acc“ field gives the R/0 or R/W access mode, which is 
changed using the commands shown below. Similarly, the parentheses 
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shown around the PIP.COM file name indicate that it has the “system" 
indicator set,, so that it will not be listed in DIR commands. The 
four command forms 

STAT d:f ilename. typ $R/0 
STAT d : f ilename . typ $R/W 
STAT d : f ilename . typ $SYS 
STAT d : f ilename . typ $DXR 

set or reset various permanent file indicators. The R/0 indicator 
places the file (or set of files) in a read-only status until changed 
oy a subsequent STAT command. The R/0 status is recorded in the 
directory with tne file so that it remains R/0 through intervening 
cold start operations. The R/W indicator places the file in a 
permanent read/write status. The SYS indicator attacnes the system 
indicator to the file, while the DIR command removes the system 
indicator. The " filename. typ“ may be ambiguous or unambiguous, but in 
either case, the files wnose attributes are changed are listed at the 
console when the change occurs. The drive name denoted by “d:" is 
optional. 

When a file is marked R/0, subsequent attempts to erase or write 
into the file result in a terminal BDOS message 

ados Err on d: File R/0 

The BDOS then waits for a console input before performing a subsequent 
warm start (a “return” is sufficient to continue) „ The command form 

. STAT a :DSK : 


lists the drive characteristics of tne disk named by ”d:“ which is in 
tne range As, Bs, The drive characteristics are listed in 
tne formats 


d: Drive Characteristics 
65536: 128 Byte record Capacity 
8192: Kilooyte Drive Capacity 
128: 32 Byte Directory Entries 
0: Checked Directory Entries 
1024: Records/ Extent 
128: Records/ Block 
58: Sectors/ Track 
2: Reserved Tracks 


where “d:“ is the selected drive, followed by the total record 
capacity (65536 is an 8 megabyte drive) , followed by the total 
capacity listed in Kiloovtes. The directory size is listed next, 
followed by the , ■checked ,, entries. The number of checked entries is 
usually identical to the directory size for removable media, since 
this mechanism is used to detect changed media during CP/M operation 
witnout an intervening warm start. For fixed media, the number is 
usually zero, since the media is not changed without at least a cold 
or warm start. The number of records per extent determines the 
addressing capacity of eacn directory entry (1024 times 128 bytes, or 
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123K in the example aoove). The number of records per clock shows the 
oasic allocation size (in the example, 128 r ecoras/olock times 128 
bytes per record, or 16K Dytes per block). The listing is then 
followed by the number of physical sectors Der track and the number of 
reserved tracks. For logical drives which share the same physical 
disk, the number of reserved tracks may be quite large, since this 
mechanism is used to skip lower-numbered disk areas allocated to otner 
logical disks. The command form 

STAT DSK : 

oroduces a drive cnaracter istics taDle for all currently active 
drives. The final STAT command form is 

STAT USR: 

which produces a list of the user numbers whicn have files on the 
currently addressed disk. The display format is: 

Active User : 2 
Active Files: 2 1 3 

where the first line lists the currently addressed user number, as set 
by the last CC? USER command, followed by a list of user numbers 
scanned from the current directory. In the above case, the active 
user numoer is a (default at cold start) , witn three user numbers 
whicn have active files on the current disk. The operator can 
subsequently examine the directories of the other user numbers by 
logging-in with USER 1, USER 2, or USER 3 commands, followed by a DIR 
command at the CC? level. 
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PIP ENHANCEMENTS 


5 . 


PIP provides three new functions whicn account for the features 
of CP/M 2.0. All three functions take the form of file parameters 
which are enclosed in square orackets following the appropriate file 
names. The commands are: 

Gn Get File from User number n 

(n in the range u - 15) 

W- tfrite over R/0 files without 

console interrogation 

R Read system files 

The G command allows one user area to receive data files from another. 
Assuming the operator has issued the USSR 4 command at the CCP level, 
tne PIP statement 


PIP X.Y = X.Y [G2] 

reads file X.Y from user number 2 into user area number 4. The 
command 

PIP A:-As * . * [G2] 

copies all of the files from the A drive di-r-ectory for user number 2 
into the A drive directory of the currently logged user number. Note 
tnat to ensure file security, one cannot copy files into a different 
area than the one which is currently addressed by the USER command. 


Note also that the PIP program itself is initially copied to a 
user area (so that subsequent files can be copied) using the SAVE 
command. The sequence of operations shown below effectively moves PIP 
from one user area to the next. 


USER 0 
DDT PIP.COM 
(note PIP size 
G0 

USER 3 

SAVE s PIP.COM 


login user 0 
load PIP to memory 
s) 

return to CCP 
login user 3 


where s is the integral number of memory ”pages• , (256 byte segments) 
occupied by PIP. The number s can be determined when PIP.COM is 
loaded under DDT, by referring to the value under the ••NEXT” display. 
If for example, the next available address is 1D00, then PIP.COM 
requires 1C hexadecimal pages (or 1 times 16 + 12 = 23 pages) , and 
tnus the value of s is 28 in the subsequent save. Once PIP is copied 
in this manner, it can then be copied to another disk belonging to the 
same user number through normal pip transfers. 

Under normal operation, PIP will not overwrite a file which is 
set to a permanent R/0 status. If attempt is made to overwrite a R/0 
file, the prompt 
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hPSTINATION FILE IS R/O, DELETE (Y/N) ? 



is issued. If the operator responds with the character “y" then the 
file is overwritten. Otnerwise, the response 

** NOT DELETED ** 

is issued, the file transfer is skippped, and PIP continues with tne 
next operation in sequence. In order to avoid the prompt and response 
in the case of R/O file overwrite, the command line can include the W 
parameter, as shown oelow 

PIP A. : =3 : * . COM [ N] 

which copies all non-system files to the A drive from the B drive, and 
overwrites any R/O files in the process. If the operation involves 
several concatenated files, the W parameter need only be included witn 
the last file in the list, as shown in the following example 

PIP A. DAT = 3 .DAT, F : NEW .DAT, G : OLD. DAT [N] 

Files with the system attribute can be included in PIP transfers 
if the R parameter is included, otherwise system files are not 
recognized. The command line 

PIP ED.COM = 3 : ED. COM [R] 

for example, reads tne ED.COM file from the B drive, even if it has 
oeen marked as a R/O and system file. The system file attributes are 
copied, if present. 


It should be noted that downward compatibility with previous 
versions of CP/M is only maintained if the file does not exceed one 
megabyte, no file attributes are set, and the file is created by user 

a. 
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6. ED ENHANCEMENTS. 


The CP/M standard orogram editor provides several new facilities 
in the 2.3 release. Experience has shown that most operators use the 
relative line numbering feature of ED, and thus the editor has the “v“ 
(Verify Line) option set as an initial value. The operator can, of 
course, disable line numoering by typing the "-v" command. If you are 
not familiar with the ED line numoer mode, you may wish to refer to 
tne Appendix in tne ED user’s guide, where the ,0 v ,t command is 
descr ibed. 

ED also takes file attributes into account. If the operator 
attempts to edit a read/only file, the message 

** FILE IS READ/ONLZ ** 

appears at the console. The file can oe loaded and examined, but 
cannot be altered in any way. Normally, the operator simply ends the 
edit session, and uses STAT to change the file attribute to R/W. If 
the edited file has the "system'* attribute set, the message 

"SYSTEM** FILE NOT ACCESSIBLE 

is displayed at the console, and the edit session is aborted. Again, 
the STAT program can be used to change the system attribute, if 
desirea. 

Finally, the insert mode ("i") command allows CRT line editing 
functions, as described in Section 2, above. 
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7. THE XSUB FUNCTION. 

An additional utility program is supplied with version 2.0 of 
CP/M, called XSUB, which extends the power of the SUBMIT facility to 
include line input to programs as well as the console command 
processor. The XSUB command is included as the first line of your 

submit file and, when executed, self-relocates directly below the CCP. 
All subsequent submit command lines are processed by XSUB, so that 
programs which read buffered console input (BDOS function 10) receive 
their input directly from the submit file. For example, the file 
SAVER. SUB could contain the submit lines: 

XSUB 

DDT 

I51.HEX 

R 

G0 

SAVE 1 52.COM 

with a subsequent SUBMIT command: 

SUBMIT SAVER X Y 

which substitutes X for $1 and Y for $2 in the command stream. The 
XSUB program loads, followed by DDT which is sent the command lines 
“IX. HEX’* "R“ and “G0" thus returning to the CCP. The final command 
“SAVE 1 Y . COM " is processed by the CCP. 

The XSUB program remains in memory, and prints the message 

(xsub active) 

on each warm start operation to indicate its presence. Subsequent 
submit command streams do not recruire the XSUB, unless an intervening 
cold start has occurred. Note that XSUB must be loaded after DESPOOL, 
if both are to run simultaneously. 
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8. 8D0S INTERFACE CONVENTIONS, 


CP/M 2 . 3 system calls take place in exactly the same manner as 
earlier versions, with a call to location 0005H, function number in 
register C, and information address in register oair DE. Single byte 
values are returned in register A, with double byte values returned in 
HL (for reasons of compatibility, register A = L and register 3 = H 
upon return in all cases). A list of CP/M 2,0 calls is 
with an asterisk following functions which, are either 
from version 1.4 to 2.0. Note that a zero value 


oufe-of range function numbers. 


is 


given below, 
new or revised 
returned for 


0 System Reset 

1 Console Input 

2 Console Output 

3 Reader Input 

4 Puncn Output 

5 List Output 

6* Direct Console I/O 
7 Get I/O Byte 
3 Set I/O Byte 
9 Print String 
10* Read Console Buffer 
11 Get Console Status 
12* Return Version Number 

13 Reset Disk System 

14 Select Disk 
15* Open File 
16 dose File 

17* Search for First 
18* Search for Next 


19* Delete File 

20 Read Sequential 

21 Write Seauential 
22* Make File 

23* Rename File 

24* Return Login Vector 

25 Return Current Disk 

26 Set DMA Address 

27 Get Addr(Alloc) 

28* Write Protect Disk 
29* Get Addr (R/O Vector) 
30* Set File Attrioutes 
31* Get Addr (Disk Farms) 
32* Set/Get User Code 
33* Read Random 

34* Write Random 
35* Comoute File Size 
36* Set Random Record 


ci 


(functions 2b, 29, and 32 should be avoided in application programs to 
maintain upward compatibility with MP/M.) The new or revised functions 
are described below. 


Function 6: Direct Console I/O. 

Direct Console I/O is supported under CP/M 2.0 for those 
applications where it is necessary to avoid the BOOS console I/O 
operations. Programs wnicn currently perform direct I/O tnrougn the 
BIOS should be cnanged to use direct I/O under BDOS so that they can 
be fully supported under future releases of MP/M and CP/M. 

Upon entry to function 6, register E eitner contains hexadecimal 
FF, denoting a console input request, or register E contains an ASCII 
character . If the input value is FF , then function 6 returns A = 00 
if no character is ready, otherwise A contains the next console incut 
cnaracter. 

If the input value in E is net FF, then function 6 assumes that 
E contains a valid ASCII character which is sent to the console. 


(All Information Contained Herein is Proprietary to Digital Research.) 


12 



Function 10: Read Console Buffer. 

The console Duffer read operation remains unchanged except that 
console line editing is supported, as described in Section 2. Note 
also that certain functions which return the carriage to the leftmost 
oosition (e.g., ctl-X) do so only to the column position where the 
prompt ended (previously, the carriage returned to the extreme left 
margin) . This new convention makes operator data input and line 
correction more legible. 


Function 12: Return 'Version Number. 


Function 12 has been redefined to orovide information which 
allows version-independent programming (this was previously the "lift 
head" function whicn returned HL=0000 in version 1.4, but performed no 
operation) . The value returned by function 12 is a two-bvte value, 
with h = 30 for the CP/M release (H = 01 for MP/M) , and L = 03 for all 
releases previous to 2.0. CP/M 2.0 returns a hexadecimal 20 in 
register L, with subsequent version 2 releases in the hexadecimal 
range 21, 22, through 2F. Using function 12, for example, you can 
write application Drograms which provide both sequential and ranaom 
access functions, with random access disabled when operating under 
early releases of CP/M. 

In the file ooerations described below, DE addresses a file 
control clock (FCS) . Further, all directory operations take place in 
a reserved area which does not affect write buffers as was the case in 
version 1.4, with the exception of Searcn First and Search Next, where 
compatioility is required. 


The File Control 3lock (FCB) 
bytes for sequential access, 
tne file is accessed randomly, 
normally located at 305CH can be used 
Dytes 007DH, 007EH, and 007FH are 

notational purposes, the FCB format 
fields: 


data area consists of a sequence of 33 
and a series of 36 bytes in the case that 
The default file control Dlock 
for random access files, since 
available for this purpose. For 
is shown with the following 
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! <3 r I f 1 1 f 2 I / / I f3 I tl 1 12 1 13 lex| si I s2 I rc| d0 I / / I dn I cr I r0 I rl I r 2 
03 01 02 ... 06 09 10 11 12 13 14 15 16 ... 31 32 33 34 35 


wner e 
dr 


drive code (G - 16) 

0 -> use default drive for file 

1 => auto disk select drive A , 

2 => auto disk select drive B, 

® ® • 

16=> auto disk select drive P. 


fl...f8 contain the file name in ASCII 
upper case, with high bit = 3 

tl,t2,t3 contain the file type in ASCII 
upper case, witn high bit - 0 
tl ' , t2‘, and t3 * denote the 
bit of these positions, 
tl ‘ = 1 => Read/Only file, 
t2 ' =1 => SYS file, no DIR list 


ex 

si 

s2 

r c 

da « 

cr 


contains the current extent number, 
normally set to 00 by the user, but 
in range 3-31 during file I/O 

reserved for internal system use 

reserved for internal system use, set 
to zero on call to OPEN, MAKE, SEARCH 

record count for extent “ex," 
takes on values from 0 - 128 

,dn filled-in by CP/M, reserved for 
system use 

current record to read or write in 
a sequential file operation, normally 
set to zero by user 


r3,rl,r2 optional random record number in the 
range 0-65535, with overflow to r2, 
r0,rl constitute a 16-bit value with 
low byte r0 , and high byte rl 


Function 15: Open File. 

Tne Open File operation is identical to previous definitions, 
with the exception that byte s2 is automatically zeroed. Note that 
previous versions of CP/M defined this byte as zero, but made no 
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cnecks to assure compliance. Thus, the byte is cleared to ensure 
upward compatiDili ty with the latest version, where it is required. 


Function 17: Searcn for First. 


Searcn First scans the directory for a match with the file given 
by the FCB addressed by DE. The value 255 (hexadecimal FF) is 
returned if the file is not found, otherwise a value of A equal to 0, 
1, 2, or 3 is returned indicating the file is present. In the case 
that the file is found, the current DMA address is filled with the 
record containing the directory entry, and the relative starting 
position is A * 32 (i.e., rotate the A register left 5 bits, or ADD A 
five times). Altnough not normally required for application programs, 
the directory information can be extracted from the buffer at this 
position. 


An ASCII question mark (63 decimal, 3F hexadecimal) in any 
position from fl through ex matches the corresponding field of any 
directory entry on the default or auto— selected disk drive. If the dr 
field contains an ASCII question mark, then the auto disk select 
function is disabled, the default disk is searched, with the search 
function returning any matched entry, allocated or free, belonging to 
any user number. This latter function 
aDDiication programs, out does allow complete 
current directory values. If the dr field is 
s2 byte is automatically zeroed. 


is not normally used by 
flexibility to scan all 
not a Question mark, the 


Function 18: Search for Next. 


The Searcn Next function is 
function, except that the directory 
matched entry. Similar to function 
decimal value 255 in A when no more dir 


similar to the S 
scan continues f 
17, function 18 
ectory items matcn. 


e 

r 

r 


arcn First 
om the last 
eturns the 


Function 19: Delete File. 

The Delete File function removes files which match the FCB 
addressed by DE. The filename and type may contain ambiguous 
references (i.e., question marks in various positions), but the drive 
select code cannot be ambiguous, as in the Search and Search Next 
functions. 

Function 19 returns a decimal 255 if the reference file or files 
could not be found, otherwise a value in the range 0 to 3 is returned. 
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Function 22: Make File* 


CP/M, 


The Make File operation is identical to previous versions 
except that byte s2 is zeroed upon entry to the 3D0S. 


of 


Function 23; Rename File. 


The Actions of the file rename functions are the same as 
previous releases except that the value 255 is returned if the rename 
function is unsuccessful (the file to rename could not be found) , 
otherwise a value in the range id to 3 is returned. 


Function 24; Return Login Vector. 


HL 

dr 

dr 

re 


The login vector value returned oy CP/M 
, where the least significant bit of L co 
ive A, and the nigh order bit of H cor 
ive, labelled p. Note that compatibility i 
leases, since registers A and l" contain the 


r 

r 

s 


2.0 is a 16-bit value in 
responds to the first 
esponds to the sixteenth 
maintained with earlier 
same values upon return. 


Function 28: Write Protect Current Disk. 


The 

protection 
the disk, 
message 


disk write protect function provides temporary write 
for the currently selected disk. Any attempt to write to 
before the next cold or warm start operation produces the 


Bdos Err on d: R/0 


Function 29: Get R/O Vector. 

Function 29 returns a bit vector in register pair HL which 
indicates drives which have the temporary read/only bit set. Similar 
to function 24, the least significant oit corresponds to drive A, 
while the most significant bit corresponds to drive p. The R/0 bit is 
set either by an explicit call to function 28, or by the automatic 
software mechanisms within CP/M whicn detect changed disks. 


Function 33: Set File Attributes. 

The Set File Attributes function allows programmatic 
manipulation of permanent indicators attached to files. In 
particular, the R/0 and System attributes (tl‘ and t2‘ above) can be 
set or reset. The DE pair addresses an unamoiguous file name with the 
appropriate attributes set or reset. Function 30 searches for a 
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matcn, and chanqes the matched directory entry to contain the selected 
inaicators. Indicators fl' through f4* are not presently used, but 
may be useful for applications programs, since they are not involved 
in the matching orocess during file open and close operations. 
Indicators f5* tnrough f3* and t3* are reserved for future system 
expansion. 


Function 31: Get Disk Parameter Block Address. 

The address of the BIOS resident disk parameter block is 
returned in HL as a result of this function call. This address can be 
used for either of two purposes. First, the disk parameter values can 
De extracted for display and space computation purposes, or transient 
programs can dynamically change the values of current disk parameters 
when the disk environment cnanges, if required. Normally, application 
programs will not require this facility. 


Function 32: Set or Get User Code. 

An application program can change or interrogate the currently 
active user number Dy calling function 3^. If register E - cF 
nexauecimal, tnen tne value of the current user number is returned in 
register A, where the value is in the range 3 to 31. If register E is 
not FF, then the current user number is changed to the value of E 
(modulo 32) . 


Function 33: Read Random. 

The Read Random function is similar to the sequential file read 
operation of previous releases, except that the read operation takes 
place at a particular record number, selected by the 24-bit value 
constructed from the three byte field following the FCB (byte 
positions r0 at 33, rl at 34, and r2 at 35). Note that the sequence 
of 24 bits is stored with least significant oyte first ( r 0 ) , middle 
pyte next (rl) , and high byte last ( r 2 ) . CP/M release 2.0 does not 
reference byte r2, except in computing the size of a file (function 
35) .• 3yte r2 must be zero, however, since a non-zero value indicates 
overflow past the end of file. 

Thus, in version 2.3, the r3,rl byte pair is treated as a 
double-byte, or ”word“ value, which contains the record to read. This 
value ranges from 3 to 65535, providing access to any particular 
record of the 8 megabyte file. In order to process a file using 
random access, the base extent (extent 3) must first be opened. 
Altnough the Dase extent may or may not contain any allocated data, 
this ensures that the file is properly recorded in the directory, and 
is visible in DIR requests. The selected record number is then stored 
into the random record field (r3,rl), and the BDOS is called to read 
the record. Upon return from the call, register A either contains an 
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error code, as listed below, or the value 00 indicating the operation 
was successful. In the latter case, the current DMA address contains 
the randomly accessed record. Note that contrary to the sequential 

read operation, the record number is not advanced. Thus, subsequent 

random read operations continue to read the same record. 

Upon each random read operation, the logical extent and current 
record values are automatically set. Thus, the file can oe 
sequentially read or written, starting from the current randomly 
accessed position. Note, however, that in this case, the last 
randomly read record will be re-read as you switch from random mode to 
sequential read, and the last record will be re-written as you switch 

to a sequential write operation. You can, of course, simply advance 

the random record position following each random read or write to 
obtain the effect of a sequential I/O operation. 

Error codes returned in register A following a random read are 
listed below. 

01 reading unwritten data 

02 (not returned in random mode) 

03 cannot close current extent 

04 seek to unwritten extent 

05 (not returned in read mode) 

06 seek past physical end of disk 

Error code 01 and 04 occur wnen a random read operation accesses a 
data clock wnicn has not been previously written, or an extent which 
has not been created, whicn are equivalent conditions. Error 3 does 
not normally occur under proper system operation, but can be cleared 
by simply re-reading, or re-opening extent zero as long as the disk is 
not physically write protected. Error code 06 occurs whenever byte r2 
is non-zero under the current 2.0 release. Normally, non-zero return 
codes can Be treated as missing data, with zero return codes 
indicating operation complete. 


• Function 34? Write Random. 

The Write Random operation is initiated similar to the Read 
Random call, except that data is written to the disk from the current 
DMA address. Further, if the disk extent or data block which is the 
target of the write has not yet been allocated, the allocation is 
performed before the write operation continues. As in the Read Random 
operation, the random record number is not changed as a result of the 
write. The logical extent number and current record positions of the 
file control block are set to correspond to the random record which is 
being written. Again, sequential read or write operations can 
commence following a random write, with the notation that the 
currently addressed record is either read or rewritten again as the 
sequential operation begins. You can also simply advance the random 
record position following each write to get the effect of a sequential 
write operation. Note that in particular, reading or writing the last 
record of an extent in random mode does not cause an automatic extent 
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in co 


witch as it does in sequential mode under either CP/M 1.4 or CP/M 

. 0 . 


The error codes returned by a random write are identical to the 
random read operation with the addition of error code 35, which 
indicates that a new extent cannot be created due to directory 
o ve r f 1 ow . 


Function 35: Compute File Size. 

When computing the size of a file, the DE reqister pair 
addresses an FC3 in random mode format (bytes r0, rl, and c2 are 
present). The FCB contains an unambiguous file name wnich is used in 
the directory scan. Upon return, the random record bytes contain the 
•■virtual" file size wnicn is, in effect, the record address of the 
record following the end of the file. if, following a call to 
function 35, the high record byte r2 is 31, then the file contains the 
maximum record count 65536 in version 2.0. Otherwise, bytes r3 and rl 
constitute a 16-bit value (r0 is the least significant byte, as 
before) which is the file size. 

Data can be appended to the end of an existing file by simply 
calling function 35 to set the random record position to the end of 
file, tnen performing a sequence of random writes starting at the 
preset record address. 

Tne virtual size of a file corresponds to the physical size when 
the file is written sequentially. If, instead, the file was created 
in random mode and "holes" exist in the allocation, then the file may 
in fact contain fewer records than the size indicates. If, for 
example, only the last record of an eight megabyte file is written in 
random mode (i.e., record number 65535), then the virtual size is 
65536 records, although only one block of data i's actually allocated. 


Function 36: Set Random Record. 

The Set Random Record function causes the 3DOS to automatically 
produce the random record position from a file which has been read or 
written sequentially to a particular point. The function can be 
useful in two ways. 

First, it is often necessary to initially read and scan a 
sequential file to extract the positions of various "key" fields. As 
each key is encountered, function 36 is called to compute the random 
record position for the data corresponding to this key. If the data 
unit size is 128 bytes, the resulting record position is placed into a 
table with the key for later retrieval. After scanning the entire 
file and tabularizing the keys and their record numbers, you can move 
instantly to a particular keyed record by performing a random read 
using the corresponding random record number which was saved earlier. 
The scheme is easily generalized when variable record lengths are 
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involved since the program -need only store the buffer-relative byte 
position along with the key and record number in order to find the 
exact starting position of the keyed data at a later time,, 

A second use of function 36 occurs when switching from -a 
sequential read or write over to random read or write. A file is 
sequentially accessed to a particular point in the file, function 36 
is called which- sets the record number, and subsequent random read and 
write operations continue from the selected point in the file. 


This section is concluded with a rather extensive, but complete 
example of random access operation. The program listed below performs 
the simple function of reading or writing random records upon command 
from the terminal. Given that the program has been created, 
assembled, and placed into a file labelled RAl 1DGM.COM, the CCP level 
command: 

RANDOM X . DAT 

starts the test program. The program looks for a file by the name 
X . DAT (in this particular case) and, if found, proceeds to prompt the 
console for input. If not found, the file is created before the 
prompt is given. Each prompt takes the form 

next command? 

and is followed by operator input, terminated by a carriage return. 
The input commands take the form 

nW nR Q 

where n is an integer value in the range 3 to 65535, and W, R, and Q 
are simple command characters corresponding to random write, random 
read, and quit processing, respectively. If the W command is issued, 
tne RANDOM program issues the prompt 

type data: 

The operator then responds by typing up to 127 characters, followed by 
a carriage return. RANDOM then writes the character string into the 
X .DAT file at record n. If the R command is issued, RANDOM reads 
record number n and displays the string value at the console. If the 
Q command is issued, the X .DAT file is closed, and the program returns 
to the console command processor. In the interest of brevity (ok, so 
the program's not so brief), the only error message is 

error, try again 

The program begins with an initialization section where the 
input file is opened or created, followed by a continuous loop at the 
label "ready where the individual commands are interpreted. The 
default file control block at 005CH and the default buffer at 0080H 
are used in all disk operations. The utility subroutines then follow. 
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whicn 

contain the 

or incipal 

input line 

processor , 

called 

-readc. " 

This 

particular 

program 

shows 

the elements 

of 

random 

access 

processing, and 

can be 

used 

as the 

basis 

for 

fur ther 

program 


development. 


* * 

* sample random access program for co/m 2.0 * 

* * 


0100 



org 

10 0h 

;base of tpa 

0000 

— 

9 

reboot 

equ 

0 0 0 0h 

; system reboot 

0005 

= 

bdos 

equ 

00 05h 

; odos entry point 

0001 

ss 

coninp 

equ 

1 

;console input function 

0002 

= 

conout 

equ 

2 

;console output function 

0009 

s 

ps tr ing 

equ 

9 

;print string until 

000a 

= 

rstr ing 

equ 

10 

;read console buffer 

0 00C 

= 

version 

equ 

12 

; return version number 

0 00f 

= 

openf 

equ 

15 

;file open function 

0810 

= 

closef 

equ 

16 

;close function 

0016 

s 

makef 

equ 

22 

;make file function 

21 

= 

reaor 

equ 

33 

;read random 

0022 

= 

wr i ter 

eau 

34 

; write random 

805c 

35 

f CO 

equ 

0 0 5cn 

;default file control block 

007a 

s 

ranrec 

equ 

fcb+33 

; random record position 

0 37f 

= 

ranovf 

equ 

fco+35 

;high order (overflow) byte 

0080 

= 

buff 

equ 

0080h 

;buffer address 

000d 

— 

9 

cr 

equ 

0dh 

^carriage return 

030a 

= 

if 

equ 

0ah 

;line feed 


.**************** *********************************** 
9 

• * * 

9 

;* load SP , set-up file for random access * 

. * * 

9 

.**********************★*****★********************** 

9 

9100 31bc0 Ixi sp, stack 


3103 0 e0c 
0105 cd0 50 
0108 f e20 
010a d21 60 

o 

013d lllbfl 
0113 cdda3 
0113 C3000 

e 

9 

versok s 


version 2.0? 
mvi c, version 

call bdos 

cpi 20h ^version 2.0 or better? 

jnc versok 

bad version, message and go back 
Ixi d ,badver 

call print 

jmp reboot 


correct version for random access 
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0116 

0e0f 


mvi 

c p openf ;open default fcb 

0118 

115c0 


Ixi 

d p fcb 

011b 

cd050 


call 

bdos 

0 lie 

3c 


inr 

a ;err 255 becomes zero 

aiif 

C2370 

e 

jnz 

ready 



9 

9 

cannot 

open file, so create it 

0122 

0el6 


mvi 

c,makef 

0124 

115c0 


Ixi 

d „ fcb 

3127 

cd050 


call 

bdos 

312a 

3c 


inr 

a ,°err 255 becomes zero 

012b 

c23 70 

© 

jnz 

ready 



9 

« 

/ 

cannot 

create file, directory full 

3 12e 

113a0 


Ixi 

d , nospace 

0131 

cdda0 


call 

print 

0134 

c3 0 0 0 


jmp 

reboot ;back to ccp 



B 

c if 



B 

?* loop back to “ready** after each command 

o is 



9 



9 

ready ; 





0 

9 

o 

file is 

ready for processing 

3137 

cde53 

9 

call 

readcom ;read next command 

013a 

227d0 


snld 

ranrec ;store input record# 

313d 

217f0 


Ixi 

h, ranovf 

0140 

3600 


mvi 

m,0 ;clear high byte if set 

3142 

fe51 


cpi 

‘Q* ;quit? 

0144 

C2560 

o 

jnz 

notq 



9 

© 

f 

quit processing, close file 

3147 

3el3 


mvi 

c,closef 

0149 

115c0 


Ixi 

a , fco 

014c 

cd350 


call 

bdos 

014f 

3c 


inr 

a ;err 255 becomes 0 

3150 

cab93 


jz 

error ;error message, retry 

0153 

C3000 


jmp 

reboot ;back to ccp 



9 



9 

; * end 

o ff 

of quit 

command, process write 



9 



notq: 





© 

9 

not the 

quit command, random write? 

3156 

f e5 7 


cpi 

*W‘ 

0158 

C2890 


jnz 

notw 



9 

• 

9 

this is 

a random write, fill buffer until - 

015b 

114d0 


Ixi 

d ,datmsg 

3 15e 

cdda3 


call 

print ;data prompt 
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3161 

3e7f 



mvi 

c , 1 27 

;up to 127 characters 

3163 

21800 



lxi 

n,Duf f 

; destination 



r loop : 

; read 

next character to buff 

3166 

c5 



pusn 

b 

;save counter 

3167 

e5 



push 

h 

;next destination 

3168 

cac20 



call 

ge tchr 

;cnaracter to a 

316o 

el 



pop 

h 

;restore counter 

316c 

cl 



DOD 

b 

;restore next to fill 

316a 

f e0d 



cpi 

cr 

;end of line? 

3 1 of 

ca783 



jz 

er looo 




• 


not end, store character 

0172 

77 



mov 

m,a 


3173 

23 



inx 

h 

;next to fill 

3174 

3d 



dcr 

c 

; counter goes down 

3175 

C2660 



jnz 

rloop 

;end of ouffer? 



erloop: 








end of read loop 

, store 30 

3178 

3630 



mvi 

m , 3 






write 

the record 

to selected record number 

317a 

3e2 2 



mvi 

c, writer 


317c 

115C0 



lxi 

d , f cb 


017f 

cd0 50 



call 

bdos 


318 2 

b7 



ora 

a 

;error code zero? 

3183 

c2b93 



jnz 

error 

;message if not 

3 lo 6 

c337j 



j mp 

ready 

;for another record 




** ******** ****** ******* 

★ it************************** 

£ 




* end 

* 

of write command. 

process read * 

* 




' 



notw: 








not a 

write command, read record? 

3189 

f e5 2 



cpi 

' R' 


318b 

c2b90 



jnz 

error 

; skip if not 




’ 

read 

random record 

3 18e 

3e21 



mvi 

c , readr 


3190 

115c0 



lxi 

d , f cb 


0193 

cd350 



call 

bdos 


3196 

hi 



ora 

a 

? return code 03? 

319 7 

c2b90 



jnz 

error 





’ 

read 

was successful, write to console 

019a 

cdcf 0 



call 

crlf 

; new line 

3 19d 

3e83 



mvi 

c , 128 

?max 128 characters 

3 19 f 

21800 



lxi 

h,buf f 

;next to get 



wloop ? 




01a2 

7e 



mov 

a,m 

ynext character 

01a3 

23 



inx 

h 

?next to get 

01a4 

e6 7f 



ani 

7 f h 

;mask parity 

01a6 

ca3 70 



jz 

ready 

;for another command if 00 

01a9 

c5 



push 

b 

;save counter 

31aa 

e5 



push 

h 

?save next to get 
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01ab 

f e20 


cpi 

jgraphic? 


! 

01ad 

d4c80 


cnc 

putenr jskip output if not 



0X130 

el 


pop 

h 



0151 

cl 


pop 

b 


O ' 

0102 

0d 


dcr 

c 7 count s count”l 


0103 

c2a20 


jnz 

wloop 



0 106 

C3370 

o 

jmp 

ready 


■ 



9 

» kkkkkktfkkiskkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 




o iS 

B 



k 



7 * end 

of read 

command,, all errors end-uo here 

k 




c * 

« 



is 



ekkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 




9 

errors 




0109 

11590 


Ixi 

d,errmsg 



01bc 

cdda0 


call 

print 



aibf 

c3 370 


jmp 

ready 




9 

9 




o * 

0 



k 




7 * utility subroutines for console i/o 

k 



• * 

9 



k 




okkkkkkkiskkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiskkiskkkk 



getchr : 

; read 

next console character to a 



0 lc2 

0e01 


mvi 

c^coninp 



01c4 

cd350 


call 

bdos 



0 lc7 

c9 


ret 






7 

putchr s 

;wr ite 

character from a to console 


o 

0 lc8 

0602 


mvi 

c,conout 



0 lea 

5f 


mov 

e,a ;character to send 



01cb 

Cd050 


call 

bdos ;send character 



31ce 

c9 


ret 






7 

crlfs 

; send 

carriage return line feed 



aicf 

3e0d 


mvi 

a,cr ;carriage return 



01dl 

cdc80 


call 

putchr 



01d4 

3e0a 


mvi 

a, If ?line feed 



01d6 

cdc80 


call 

putchr 



31d9 

c9 


ret 





pr int: 




; print 

the buffer addressed by de until 

$ 

01da 

d5 

push 

d 


0 Idb 

edef 0 

call 

cr If 


0 Ide 

dl 

pop 

d ;new line 


aidf 

0e09 

mvi 

c,pstrina 


0 lei 

cd050 

call 

bdos jprint the string 


31e4 

c9 

ret 




9 

readcom : 
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0 

0 

a 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 


0 

0 

0 

0 

0 






; r ead 

the next command line to the conbuf 

le5 

116b0 



ixi 

d, prompt 

le8 

cdda0 



call 

orint ; command? 

leb 

0e0a 



mvi 

c , rstr ing 

led 

117a0 



lxi 

d , conbuf 

1 f 0 

cd0 50 



call 

bdos ;read command line 




’ 

command line is Dresent, scan it 

If 3 

21000 



lxi 

h,0 ; start with 0000 

If 6 

117c0 



lxi 

d ,conlin; command line 

If 9 

la 

readc: 

ldax 

d ;next command cnaracter 

If a 

13 



inx 

d ; to next command Dosition 

lfb 

b7 



ora 

a ; cannot be end of command 

lfc 

c8 



rz 






not ze 

ro, numeric? 

lfd 

d630 



sui 

'0 ' 

Iff 

f e0a 



cpi 

10 ; carry if numeric 

201 

d2130 



jnc 

endrd 





add-in 

next digit 

204 

29 



dad 

h ; *2 

205 

4d 



mov 

c,l 

206 

44 



mov 

b,h ; oc = value * 2 

207 

29 



dad 

h ; *4 

203 

29 



dad 

h ; *8 

209 

09 



dad 

b ; *2 + *8 = *10 

20a 

85 



add 

1 ;+digit 

2ao 

br 



mov 

1 ,a 

20c 

d2f 90 



jnc 

readc ;for another char 

20f 

24 



inr 

h ;overflow 

210 

c3f 90 



jmp 

readc ;for another char 



enard: 







end of 

read, restore value in a 

213 

c630 



adi 

'0' ; command 

215 

f e61 



coi 

'a' ;translate case? 

217 

d8 



rc 






lower 

case, mask lower case bits 

213 

e65f 



ani 

10 l?llllb — 

21a 

c9 



ret 









* string data 

* 

area for console messages * 

* 







oadver : 

021b 

536f79 

db 


nospace: 

023a 

4e6f 29 

db 


datmsg : 

0 24d 

547970 

db 


er rmsg : 

0259 

457272 

db 


prompt: 

0260 

4e6 570 

db 


'sorry, you need cp/rn version 2$’ 
'no directory space?' 

' type data: 5 ' 

'error, try again.?' 

'next command? ?' 


(All Information Contained Herein is Proprietary 


to Digital 


Research. ) 


25 


027a 
027b 
027c 
0 0 21 

0 29c 

0 2bc 


(All 





« it 


* 


;* fixed and 
• * 

variable data area * 

* 


t 

vieieleiKlgicieisicIticieieieieisicicIgis'klciticieleitiele’kie'Xisigicieicicleie'k'kigleicig'Xie-k'kie 

a 

21 

conbuf; db 

conlen 

;length of console buffer 


consiz: as 

1 

^resulting size after read 


conlin: ds 

32 

^length 32 buffer 

- 

conlen equ 

$-consiz 



ds 

32 

; 16 level stack 


stack ; 




end 
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